home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Original Shareware 1.1
/
The Original Shareware (WeMake CDs)(Volume 1.1)(CDs, Inc)(1993).iso
/
6
/
cl0588.zip
/
CL.DOC
next >
Wrap
Text File
|
1988-05-01
|
28KB
|
727 lines
Documentation for Clist, version 05.01.88
CLIST
C Source listing utility
by
John Hardin
Clist is a utility for listing "C" language source files
with various formatting options. Available options include
highlighting of keywords, graphic connection of { } pairs,
forcing of a new page at the beginning/ending of include
files and/or functions, and cross-reference of functions,
variables and constants.
Clist does the following formatting automatically: Pages
are numbered and titled as to date of listing, source file
being listed and include file currently being listed. The
source file can also specify two lines of title text which
can be changed at any time.
Clist will include files specified in #include
statements. Depth of inclusion is effectively unlimited, and
inclusion may be controlled by directives within the source
file. Clist will search specified paths for #include files.
Clist will print multiple copies of multiple source
files from one invocation of the Clist program. Clist's
output is sent to the standard output, so it can be sent to
either the printer or a file using the DOS redirection
facilities.
Clist can be reconfigured for use on a variety of
printers with a great deal of ease, through the use of a
configuration file that Clist references upon execution.
Clist requires MS-DOS version 2.0 or later, at least
256k of RAM, and a printer (the printer being handy but not
absolutely essential). Clist has also been tested and works
under SCO VP/ix version 1.0, but it displays some minor bugs
that don't occur with normal MS-DOS. A Xenix version is in
the works...
1
Documentation for Clist, version 05.01.88
RUNNING CLIST
To get a brief description of the Clist command-line,
type:
A>CL
This will display the command line format as well as the
switches Clist recognizes.
The basic command line format for calling Clist is:
A>CL {-switch} ufn {{-switch} ufn} >destination
where {...} means ... is repeated zero or more times.
Valid switches consist of a dash `-' followed by one or
more letters or a numeral, depending on the switch. The valid
switches are:
-G Control graphics connection of { } pairs
-H Control highlighting of keywords.
-S Initially suppress listing the source code
(useful for getting just a cross-reference).
A /*.list*/ will start listing source code.
-I Initially list include files. If you don't
want to list includes and you don't want to
edit the files to put in a /*.noincl*/, say
CL -!I ...
-PBI Force a new page at the beginning of
each included file.
-PAI Force a new page at the end of each
included file.
-PBF Force a new page at the beginning of
each function.
-PAF Force a new page at the end of each
function.
-C & Cross-reference functions and
-CFV variables/constants
-CF Cross-reference functions only
-CV Cross-reference variables/constants only
-CG Cross-reference across all files on command
line (also -CGF and -CGV)
2
Documentation for Clist, version 05.01.88
The -C, -G, -H, -S, -I and -P switches work as follows:
-switch Turn function on.
-!switch Turn function off.
These are samples of valid Clist command lines:
A>cl -c-g hack.c >prn
Clist will list the file HACK.C, cross-referencing
functions and variables and graphically connecting { } pairs,
and will send the listing to the printer.
A>cl -paf clib >prn
Clist will list the file CLIB.C, forcing a new page at
the end of each function, and will send the listing to the
printer.
A>cl homework. >hmwk.lst
Clist will list HOMEWORK doing no fancy formatting, and
will send the listing to the file HMWK.LST for spooling,
archiving, etc. Note the difference from the previous
example! The hanging period overrides the automatic .C
assumption.
A>cl -cf proga.c -!c progb.c >prn
Clist will list PROGA.C, cross-referencing functions,
and will send the listing to the printer. Clist will then
list PROGB.C without cross-referencing, and will send the
listing to the printer. In this case, it would be less effort
to say:
A>cl progb.c -cf proga.c >prn
which would produce the same results, albeit the listings
would be in different order.
A>cl -cg mod1 mod2 mod3 > xx
Clist will list modules mod1.c, mod2.c and mod3.c to
file xx, then will list a cross-reference for all three files
(useful for finding global variables and cross-module
function calls)
3
Documentation for Clist, version 05.01.88
SEARCHING FOR FILES
If you wish to list source or #include files that are
not in the current directory, you may specify that Clist
search for them in other directories or other disks, similar
to the way MS-DOS searches for .COM and .EXE files. If the
environment variables INCLUDE or EINCLUDE exist, Clist
assumes they specify which directories or drives needed files
are to found in or on. The search paths must be separated by
semicolons and must not have embedded spaces. For example,
A>set include=c:\prog\c\incls;c:\prog\c\headrs;b:\
would tell Clist to look for files in the current directory,
then in the directory named C:\PROG\C\INCLS, then in the
directory named C:\PROG\C\HEADRS, then in B:\ (the root
directory of the B: drive). If the needed file is not in any
of these directories, Clist will not list that file.
You can also specify an alternate environment variable
in the configuration file if your C compiler does not use
INCLUDE or EINCLUDE. If you specify an alternate it will
replace EINCLUDE.
CLIST DIRECTIVES
The behavior of Clist is also controlled by directives
embedded within the source code. These directives all begin
with a period, and all occur within comments. Clist will only
see directives that are in the first level of comments, so a
directive can be rendered ineffective without removing it by
placing a second set of comment delimiters around it
(assuming, of course, your compiler will allow comments to be
nested):
/* .seen /* .ignored */ */
Valid directives consist of a period followed by one or
more letters. Only as many letters as needed to uniquely
specify a directive must be typed, meaning `.p' is the same
as `.page'. The valid directives are:
.page force a new page after printing this line
.title The text that follows up to the first */,
excluding leading blanks, one formatting
character at the beginning and trailing
blanks, is to be printed as the first line
of the page title.
.subtitle The text that follows (as above) is to be
printed as the second line of the page
title.
4
Documentation for Clist, version 05.01.88
.author The text that follows (as above) is to be
printed as the author's name, job code, etc.
.nolist Suspend output of the listing after
printing this line.
.list Resume output of the listing, beginning with
this line. (Default unless -S on command
line)
.noinclude Suspend inclusion of files appearing in
#include statements.
.include Resume inclusion of files appearing in
#include statements. (Default)
.nofunction Suspend listing the current function's name
at the top of each page. (Default)
.function Resume listing the current function's name
at the top of each page.
.lzero Print page numbers with leading zeroes.
(Default)
.nolzero Print page numbers without leading zeroes.
The text in .title, .subtitle and .author directives may
be formatted by placing one of the following characters
before the text:
`|' Print the text centered on the page.
`>' Print the text right-flush on the page.
`<' Return the text to it's previous value.
'0' Create a new, empty text string.
If no formatting characters appear, the text is printed
flush left. All leading and trailing blanks are stripped. For
example,
/*.title | C program */
would make the first line of the title "C program" centered
in the page, and
/*.t < last title */
will make the title whatever it was before the last .title
directive. The "last title" is ignored.
A suggested way to use .title and .subtitle is to make
the first line of the main source file set the title text to
5
Documentation for Clist, version 05.01.88
a short description of the entire program, then have the
first line of each file set the subtitle text to a short
description of that file. Each include file would then do a
/*.st<*/ at it's end to restore the previous subtitle.
AUTOMATIC FORMATTING
Clist automatically titles each page with a line telling
when the listing was produced, what the main source file is,
and which include file is currently being listed. Each page
is numbered.
Each line is preceded by two numbers separated by a
slash. The first number is the number of the line in the
entire listing. The second number is the number of the line
in the file it appears in. For example,
1000/100 blah blah blah blah
means this line is the 1000th line of the listing, and the
100th line in the file being listed. This makes it easier to
pinpoint an error after finding it in the listing.
The format for cross-reference entries is:
Name of token
page of listing this occurrence appears on
listing line this occurrence appears in
name of the file this occurrence appears in
line this occurrence appears in within that file
name of the function this occurrence appears in, or
"defined" if it doesn't appear inside a function.
CONFIGURATION FILE
If the file CL.CNF exists in the current directory or
along PATH, or an alternate file specified in the environment
variable CLCONFIG exists, Clist will treat it's contents as
configuration information, and will open and read it before
beginning the listing process. The format for the
configuration file is as follows:
# COMMENT - Everything on a line after a # is ignored
# blank lines are also ignored.
# In both commands and arguments (except for literal
# characters), case is ignored, so WiDTh == width
# Values may be specified in six ways:
# . decimal numbers 0 to 255
# . hexadecimal numbers x0 to xFF
# . octal numbers o0 to o377
# . control characters ^O, ^Z, etc.
# . literal characters 'G', '|', etc.
# in literal characters the following MUST be escaped
6
Documentation for Clist, version 05.01.88
# with a preceding \ character: ,;'#\ and whitespace
# . the escape character, esc
# 27, x1b, ^[ and ESC are all equivalent.
width = 132; # This specifies the width in characters of
# a printed line, after the printer initial-
# ization string has been sent, is 132.
margin = 5; # This specifies to leave a five-space margin
# at the left edge of the paper (for hole
# punches, etc.)
length = 66; # This specifies the length of the paper in
# lines after the printer initialization
# string has been sent is equal to 66.
depth = 8; # This specifies that Clist will allow 8
# spaces for block connection at first.
tabs = 4; # This specifies that tab characters will
# be expanded to simulate tab stops every
# 4 characters.
search = "INCLUDE"; # Additional environment variable
# to use as a path to find #include files - the
# only one that accepts a string argument.
# Escape special characters ,;'"#\ and whitespace!
# The string MUST be capitalized.
# Printer control strings (PCSs) may be up to sixty (60)
# characters in length, and may contain zero bytes (\0).
# Bytes in a PCS are separated by a comma, and the PCS
# is terminated by a semicolon. A PCS may be zero
# length, in which case it is not sent to the printer.
# Examples:
init = ^o; # sets the printer initialization PCS to
# one character, namely a ^O.
init = 15;
init = xf; # Both are equivalent to the above.
normal = esc,'G';
# PCS NORMAL is sent to the printer
# upon completion of a listing.
# The other PCS commands are:
bdark ; # Code sent to begin emphasizing text
# (used to highlight keywords).
# This is how a zero-length PCS is coded.
edark ; # Code sent to end emphasizing text
bcntl ; # Code send before a control code
ecntl = 27, # Code send after a control code
'G', # (In the listing Clist produces, control
xff; # codes are mapped to letters, meaning
# a ^O in the source will become
# (bcntl)O(ecntl)
# PCSs may be split across lines.
hline ; # Code to produce horizontal line when
# connecting { } pairs
vline ; # Code to produce vertical line as above
7
Documentation for Clist, version 05.01.88
tcrnr ; # Code to produce top corner as above
bcrnr ; # Code to produce bottom corner as above
# ,- tcrnr hline
# | vline
# `- bcrnr hline
double = true;
# DOUBLE is a special case: if your printer does not do
# any special effects, you may still emphasize keywords
# by specifying double = true, which will cause Clist to
# emphasize keywords by printing letter(backspace)letter.
# Otherwise, leave DOUBLE out of your .CNF file.
Clist defaults to using codes for an Epson MX-80 without
Graftrax. CL.CNF is not required for the operation of Clist,
and may be left off if your printer is an MX-80 (or
equivalent).
Configurable characteristics and their keywords are:
KEYWORD CHARACTERISTIC
width printer line width in characters
length printer page length in lines
margin margin at left edge for binding
depth space allowed for nesting
tabstops number of spaces for a TAB
searchpath secondary search path env. var.
initialize printer initialization PCS
normal return printer to normal PCS
bdark PCS to begin highlighting
edark PCS to end highlighting
doublestrike Highlight by doublestriking?
bcntl PCS before a control character
ecntl PCS after a control character
hline horizontal connection line
vline vertical connection line
tcrnr top corner of connection line
bcrnr bottom corner of connection line
Miscellaneous other garbage
Clist is a being distributed under a variant of the
Freeware system, so you are allowed (even encouraged) to make
copies of the Clist archive, and to donate those copies to
your friends, enemies and total strangers, and to upload them
to your favorite (and not so favorite) bulletin boards.
Clist is available free of any monetary obligation, but
if you use the program regularly and like it, a small
donation to the author would be welcomed ($20 is suggested).
In addition, if you send a blank, formatted disk and return
postage with your donation, you will get a complete copy of
the latest version of Clist. Also, if you have any gripes,
comments or suggestions, please don't hesitate to write.
8
Documentation for Clist, version 05.01.88
Along with this distribution scheme go a few small
responsibilities that you should fulfill:
o Since the sign-on message isn't offensive,
don't alter it.
o Also, don't tinker with the program or
documentation then distribute the results
as the original item.
o Clist is a stand-alone program, but it's
nice to have the documentation, too. Don't
split them up.
o You MAY NOT charge a fee for distribution of
copies of the program or documentation.
These are not difficult to follow, and are directed at
making life easier for the guys on down the line.
"The first thing we do, let's kill all the lawyers."
- Shakespeare
(probably a misquote)
DISCLAIMER
In no event shall the author of this program be liable
for any damages, material or otherwise, arising from the use
(or misuse) or this program. Suitability and functionality of
this program is not guaranteed. The responsibilities of the
author shall be limited to supplying a replacement copy of
the archive, providing the conditions stated above have been
met.
Misfeatures and warnings
Clist is great at producing large volumes of output. Be
careful when trying to list large files, especially when
cross-referencing.
Clist sees program name extensions as directives if they
are in comments, so you may get some "Unknown Directive"
warnings. Clist ignores the standard ".c" and ".h"
extensions, so in most cases this particular annoyance won't
occur. Putting program names and abbreviations (i.e. "i.e.")
two comment levels deep will prevent this.
If you are prototyping functions, the semicolon that
comes after the formal parameter list or parameter types must
be on the same line as the beginning of the function
prototype, otherwise Clist will see the prototype as a
function definition. The same holds true for function
declarations.
Also, function definitions, declarations and calls that
span lines, i.e.:
9
Documentation for Clist, version 05.01.88
func
(a,b,c)
will be interpreted as variables rather than functions when
cross-referencing. Declare functions and prototypes like this
to be safe:
void func(int a, int b);
^ on the same line for prototypes!
And if you write null functions like this:
null()
{}
Clist won't be able to tell where the function ends. This
won't cause any problems, except perhaps cosmetic ones if you
are using the .function directive. Put the { and } on
separate lines.
If you have downloaded your copy of this archive from a
BBS, it may be a subset (teaser copy) of the complete Clist
program described above. If this is the case, the version
number ends in S. The subset version of Clist does not cross-
reference, connect blocks or highlight keywords, which are
Clist's best features. To obtain a complete copy, send a
donation and a blank disk with return postage as stated
above.
Please direct all correspondence to:
John Hardin, KA7OHZ
1215 E. 1700 So. Apt. B
Salt Lake City, UT 84105
Compuserve: 74076,22
- Be sure to read the file READ.ME -
Comments - especially printer configuration information - are
eagerly solicited!
10
Documentation for Clist, version 05.01.88
Program history
(minor tweaking and frobbing omitted)
October 1986 - Development commenced, using Toolworks
C version 3.2M
December 1986 - Ported to Data General Eclipse
under AOS-VS 6.00
- Ported to Eco-C version 3.17
- Clist released upon the unsuspecting
public
- Bug that prevented recognition of VOID
and ENUM keywords fixed
- .author and .function added
March 1987 - Bug that prevented recognition of error
on write fixed
- Handling of exhaustion of cross-ref
allocation space improved
May 1987 - Handling of block nesting exceeding
space allowed for by DEPTH improved
August 1987 - Added CONST and VOLATILE keywords to
support Microsoft C version 5.0
January 1988 - Ported to ECOC-88 Release 4.0
- Changed configuration routine to use a
generic configurator - configuration
file format changed slightly.
- Added searchpath, CLCONFIG, -S and
title/subtitle/author stacks
- Fixed source file pathname handling bug
April 1988 - Ported to Turbo C version 1.5
- Recompiled using compact model, allowing
access to 1M of data
- Added -I command line switch
- Lots of minor bugs squashed
- Compiled a '286 version
- Expanded PCSs to 60 characters for
laserjets and other talkative printers
- Added command-line wildcard expansion
(Thanks to John Maline's Turbo-C module
ARGV from BIX)
May 1988 - Added global cross-referencing
- Modified connecting lines to leave only
one leading blank before the program
text
** end of documentation **
